import { Meta } from "@storybook/addon-docs/blocks";
import { Badge } from "storybook/internal/components";

<Meta title="Docs/Figma (Figspec)/README" />

# Embedding Figma designs via Figspec

This document describes how to embed your Figma files/frames to your Storybook
using <a href="https://github.com/pocka/figspec">Figspec</a>.

You can embed Figma files or frames with enhanced spec viewer (Figspec) with `figspec` type.
The addon calls Figma API with provided Figma Token and renders your Figma files or frames using Figspec components with the result.

**This feature requires you to include your Figma API Access Token to Storybook bundle.
Make sure your Storybook is private and understand the risk.**

## Limitations

Since `@figspec/components` being WebComponents, browser support is limited to those support CustomElements v1 and Shadow DOM.

## Usage

Put a `design` parameter into your story with `type: "figspec"` and `url` pointing your Figma file/frame/prototype.

You also provide your [Figma Personal Access Token](https://www.figma.com/developers/api#access-tokens) in `accessToken` field or `STORYBOOK_FIGMA_ACCESS_TOKEN` environment variable.

```js
export const myStory = () => <MyComponent />;

myStory.parameters = {
  design: {
    type: "figspec",
    url: "<YOUR_FIGMA_ITEM_URL>",
    accessToken: "<YOUR_FIGMA_ACCESS_TOKEN>",
  },
};
```

```sh
$ STORYBOOK_FIGMA_ACCESS_TOKEN=xxxx npm run storybook
```

## Parameter options

| Option name                                             | Type           | Default value | Description                             |
| ------------------------------------------------------- | -------------- | ------------- | --------------------------------------- |
| `type` <Badge status="positive">required</Badge>        | `"figspec"`    |               | Fixed parameter.                        |
| `url` <Badge status="positive">required</Badge>         | `string` (URL) |               | An URL to a Figma file/frame/prototype. |
| `accessToken` <Badge status="positive">required</Badge> | `string`       |               | Your Figma Personal Access Token.       |
